home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / awt / CheckboxMenuItem.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  10.7 KB  |  346 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)CheckboxMenuItem.java    1.39 98/08/19
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.awt.peer.CheckboxMenuItemPeer;
  17. import java.awt.event.*;
  18. import java.io.ObjectOutputStream;
  19. import java.io.ObjectInputStream;
  20. import java.io.IOException;
  21.  
  22.  
  23. /**
  24.  * This class represents a check box that can be included in a menu.
  25.  * Clicking on the check box in the menu changes its state from
  26.  * "on" to "off" or from "off" to "on."
  27.  * <p>
  28.  * The following picture depicts a menu which contains an instance
  29.  * of <code>CheckBoxMenuItem</code>:
  30.  * <p>
  31.  * <img src="doc-files/MenuBar-1.gif"
  32.  * ALIGN=center HSPACE=10 VSPACE=7>
  33.  * <p>
  34.  * The item labeled <code>Check</code> shows a check box menu item
  35.  * in its "off" state.
  36.  * <p>
  37.  * When a check box menu item is selected, AWT sends an item event to
  38.  * the item. Since the event is an instance of <code>ItemEvent</code>,
  39.  * the <code>processEvent</code> method examines the event and passes
  40.  * it along to <code>processItemEvent</code>. The latter method redirects
  41.  * the event to any <code>ItemListener</code> objects that have
  42.  * registered an interest in item events generated by this menu item.
  43.  *
  44.  * @version 1.39, 08/19/98
  45.  * @author     Sami Shaio
  46.  * @see         java.awt.event.ItemEvent
  47.  * @see         java.awt.event.ItemListener
  48.  * @since       JDK1.0
  49.  */
  50. public class CheckboxMenuItem extends MenuItem implements ItemSelectable {
  51.  
  52.     static {
  53.         /* ensure that the necessary native libraries are loaded */
  54.     Toolkit.loadLibraries();
  55.         initIDs();
  56.     }
  57.  
  58.     /*
  59.     * The state of a checkbox menu item
  60.     * @serial
  61.     * @see getState()
  62.     * @see setState()
  63.     */
  64.     boolean state = false;
  65.  
  66.     transient ItemListener itemListener;
  67.  
  68.     private static final String base = "chkmenuitem";
  69.     private static int nameCounter = 0;
  70.  
  71.     /*
  72.      * JDK 1.1 serialVersionUID
  73.      */
  74.      private static final long serialVersionUID = 6190621106981774043L;
  75.  
  76.     /**
  77.      * Create a check box menu item with an empty label.
  78.      * The item's state is initially set to "off."
  79.      * @since   JDK1.1
  80.      */
  81.     public CheckboxMenuItem() {
  82.     this("", false);
  83.     }
  84.  
  85.     /**
  86.      * Create a check box menu item with the specified label.
  87.      * The item's state is initially set to "off."
  88.  
  89.      * @param     label   a string label for the check box menu item,
  90.      *                or <code>null</code> for an unlabeled menu item.
  91.      */
  92.     public CheckboxMenuItem(String label) {
  93.     this(label, false);
  94.     }
  95.  
  96.     /**
  97.      * Create a check box menu item with the specified label and state.
  98.      * @param      label   a string label for the check box menu item, 
  99.      *                     or <code>null</code> for an unlabeled menu item.
  100.      * @param      state   the initial state of the menu item, where
  101.      *                     <code>true</code> indicates "on" and
  102.      *                     <code>false</code> indicates "off."
  103.      * @since      JDK1.1
  104.      */
  105.     public CheckboxMenuItem(String label, boolean state) {
  106.         super(label);
  107.         this.state = state;
  108.     }
  109.  
  110.     /**
  111.      * Construct a name for this MenuComponent.  Called by getName() when
  112.      * the name is null.
  113.      */
  114.     String constructComponentName() {
  115.         synchronized (getClass()) {
  116.         return base + nameCounter++;
  117.     }
  118.     }
  119.  
  120.     /**
  121.      * Creates the peer of the checkbox item.  This peer allows us to
  122.      * change the look of the checkbox item without changing its
  123.      * functionality.
  124.      * Most applications do not call this method directly.
  125.      * @see     java.awt.Toolkit#createCheckboxMenuItem(java.awt.CheckboxMenuItem)
  126.      * @see     java.awt.Component#getToolkit()
  127.      */
  128.     public void addNotify() {
  129.         synchronized (getTreeLock()) {
  130.         if (peer == null)
  131.             peer = Toolkit.getDefaultToolkit().createCheckboxMenuItem(this);
  132.         super.addNotify();
  133.     }
  134.     }
  135.  
  136.     /**
  137.      * Determines whether the state of this check box menu item
  138.      * is "on" or "off."
  139.      * @return      the state of this check box menu item, where
  140.      *                     <code>true</code> indicates "on" and
  141.      *                     <code>false</code> indicates "off."
  142.      * @see        java.awt.CheckboxMenuItem#setState
  143.      */
  144.     public boolean getState() {
  145.     return state;
  146.     }
  147.  
  148.     /**
  149.      * Sets this check box menu item to the specifed state.
  150.      * The boolean value <code>true</code> indicates "on" while
  151.      * <code>false</code> indicates "off."
  152.      * @param      b   the boolean state of this
  153.      *                      check box menu item.
  154.      * @see        java.awt.CheckboxMenuItem#getState
  155.      */
  156.     public synchronized void setState(boolean b) {
  157.     state = b;
  158.     CheckboxMenuItemPeer peer = (CheckboxMenuItemPeer)this.peer;
  159.     if (peer != null) {
  160.         peer.setState(b);
  161.     }
  162.     }
  163.  
  164.     /**
  165.      * Returns the an array (length 1) containing the checkbox menu item
  166.      * label or null if the checkbox is not selected.
  167.      * @see ItemSelectable
  168.      */
  169.     public synchronized Object[] getSelectedObjects() {
  170.         if (state) {
  171.             Object[] items = new Object[1];
  172.             items[0] = label;
  173.             return items;
  174.         }
  175.         return null;
  176.     }
  177.  
  178.     /**
  179.      * Adds the specified item listener to receive item events from
  180.      * this check box menu item.
  181.      * If l is null, no exception is thrown and no action is performed.
  182.      *
  183.      * @param         l the item listener
  184.      * @see           java.awt.event.ItemEvent
  185.      * @see           java.awt.event.ItemListener
  186.      * @see           java.awt.Choice#removeItemListener
  187.      * @since         JDK1.1
  188.      */
  189.     public synchronized void addItemListener(ItemListener l) {
  190.     if (l == null) {
  191.         return;
  192.     }
  193.         itemListener = AWTEventMulticaster.add(itemListener, l);
  194.         newEventsOnly = true;
  195.     }
  196.  
  197.     /**
  198.      * Removes the specified item listener so that it no longer receives
  199.      * item events from this check box menu item.
  200.      * If l is null, no exception is thrown and no action is performed.
  201.      *
  202.      * @param         l the item listener
  203.      * @see           java.awt.event.ItemEvent
  204.      * @see           java.awt.event.ItemListener
  205.      * @see           java.awt.Choice#addItemListener
  206.      * @since         JDK1.1
  207.      */
  208.     public synchronized void removeItemListener(ItemListener l) {
  209.     if (l == null) {
  210.         return;
  211.     }
  212.         itemListener = AWTEventMulticaster.remove(itemListener, l);
  213.     }
  214.  
  215.     // REMIND: remove when filtering is done at lower level
  216.     boolean eventEnabled(AWTEvent e) {
  217.         if (e.id == ItemEvent.ITEM_STATE_CHANGED) {
  218.             if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0 ||
  219.                 itemListener != null) {
  220.                 return true;
  221.             }
  222.             return false;
  223.         }
  224.         return super.eventEnabled(e);
  225.     }
  226.  
  227.     /**
  228.      * Processes events on this check box menu item.
  229.      * If the event is an instance of <code>ItemEvent</code>,
  230.      * this method invokes the <code>processItemEvent</code> method.
  231.      * If the event is not an item event,
  232.      * it invokes <code>processEvent</code> on the superclass.
  233.      * <p>
  234.      * Check box menu items currently support only item events.
  235.      * @param        e the event
  236.      * @see          java.awt.event.ItemEvent
  237.      * @see          java.awt.CheckboxMenuItem#processItemEvent
  238.      * @since        JDK1.1
  239.      */
  240.     protected void processEvent(AWTEvent e) {
  241.         if (e instanceof ItemEvent) {
  242.             processItemEvent((ItemEvent)e);
  243.         return;
  244.         }
  245.     super.processEvent(e);
  246.     }
  247.  
  248.     /**
  249.      * Processes item events occurring on this check box menu item by
  250.      * dispatching them to any registered <code>ItemListener</code> objects.
  251.      * <p>
  252.      * This method is not called unless item events are
  253.      * enabled for this menu item. Item events are enabled
  254.      * when one of the following occurs:
  255.      * <p><ul>
  256.      * <li>An <code>ItemListener</code> object is registered
  257.      * via <code>addItemListener</code>.
  258.      * <li>Item events are enabled via <code>enableEvents</code>.
  259.      * </ul>
  260.      * @param       e the item event.
  261.      * @see         java.awt.event.ItemEvent
  262.      * @see         java.awt.event.ItemListener
  263.      * @see         java.awt.CheckboxMenuItem#addItemListener
  264.      * @see         java.awt.MenuItem#enableEvents
  265.      * @since       JDK1.1
  266.      */
  267.     protected void processItemEvent(ItemEvent e) {
  268.         if (itemListener != null) {
  269.             itemListener.itemStateChanged(e);
  270.         }
  271.     }
  272.  
  273.     /**
  274.      * Returns the parameter string representing the state of this check
  275.      * box menu item. This string is useful for debugging.
  276.      * @return     the parameter string of this check box menu item.
  277.      */
  278.     public String paramString() {
  279.     return super.paramString() + ",state=" + state;
  280.     }
  281.  
  282.     /* Serialization support.
  283.      */
  284.     
  285.     /*
  286.     * Serial Data Version
  287.     * @serial
  288.     */
  289.     private int checkboxMenuItemSerializedDataVersion = 1;
  290.  
  291.     /**
  292.     * Writes default serializable fields to stream.  Writes
  293.     * a list of serializable ItemListener(s) as optional data.
  294.     * The non-serializable ItemListner(s) are detected and
  295.     * no attempt is made to serialize them.
  296.     *
  297.     * @serialData Null terminated sequence of 0 or more pairs.
  298.     *             The pair consists of a String and Object.
  299.     *             The String indicates the type of object and
  300.     *             is one of the following :
  301.     *             itemListenerK indicating and ItemListener object.
  302.     *
  303.     * @see AWTEventMulticaster.save(ObjectOutputStream, String, EventListener)
  304.     * @see java.awt.Component.itemListenerK
  305.     */
  306.     private void writeObject(ObjectOutputStream s)
  307.       throws java.io.IOException
  308.     {
  309.       s.defaultWriteObject();
  310.  
  311.       AWTEventMulticaster.save(s, itemListenerK, itemListener);
  312.       s.writeObject(null);
  313.     }
  314.  
  315.     /*
  316.     * Read the ObjectInputStream and if it isnt null
  317.     * add a listener to receive item events fired
  318.     * by the Checkbox menu item.
  319.     * Unrecognised keys or values will be Ignored.
  320.     * @serial
  321.     * @see removeActionListener()
  322.     * @see addActionListener()
  323.     */
  324.     private void readObject(ObjectInputStream s)
  325.       throws ClassNotFoundException, IOException
  326.     {
  327.       s.defaultReadObject();
  328.  
  329.       Object keyOrNull;
  330.       while(null != (keyOrNull = s.readObject())) {
  331.     String key = ((String)keyOrNull).intern();
  332.  
  333.     if (itemListenerK == key)
  334.       addItemListener((ItemListener)(s.readObject()));
  335.  
  336.     else // skip value for unrecognized key
  337.       s.readObject();
  338.       }
  339.     }
  340.  
  341.     /**
  342.      * Initialize JNI field and method IDs
  343.      */
  344.     private static native void initIDs();
  345. }
  346.